<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<!--NewPage-->
<HTML>
<HEAD>
<TITLE>
com.google.gwt.http.client (Google Web Toolkit Javadoc)
</TITLE>

<META NAME="keywords" CONTENT="com.google.gwt.http.client package">

<LINK REL ="stylesheet" TYPE="text/css" HREF="../../../../../stylesheet.css" TITLE="Style">

<SCRIPT type="text/javascript">
function windowTitle()
{
    parent.document.title="com.google.gwt.http.client (Google Web Toolkit Javadoc)";
}
</SCRIPT>
<NOSCRIPT>
</NOSCRIPT>

</HEAD>

<BODY BGCOLOR="white" onload="windowTitle();">


<!-- ========= START OF TOP NAVBAR ======= -->
<A NAME="navbar_top"><!-- --></A>
<A HREF="#skip-navbar_top" title="Skip navigation links"></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
<TR>
<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_top_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
  <TR ALIGN="center" VALIGN="top">
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <FONT CLASS="NavBarFont1">Class</FONT>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
  </TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
</EM>
</TD>
</TR>

<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
&nbsp;<A HREF="../../../../../com/google/gwt/dom/client/package-summary.html"><B>PREV PACKAGE</B></A>&nbsp;
&nbsp;<A HREF="../../../../../com/google/gwt/i18n/client/package-summary.html"><B>NEXT PACKAGE</B></A></FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
  <A HREF="../../../../../index.html?com/google/gwt/http/client/package-summary.html" target="_top"><B>FRAMES</B></A>  &nbsp;
&nbsp;<A HREF="package-summary.html" target="_top"><B>NO FRAMES</B></A>  &nbsp;
&nbsp;<SCRIPT type="text/javascript">
  <!--
  if(window==top) {
    document.writeln('<A HREF="../../../../../allclasses-noframe.html"><B>All Classes</B></A>');
  }
  //-->
</SCRIPT>
<NOSCRIPT>
  <A HREF="../../../../../allclasses-noframe.html"><B>All Classes</B></A>
</NOSCRIPT>


</FONT></TD>
</TR>
</TABLE>
<A NAME="skip-navbar_top"></A>
<!-- ========= END OF TOP NAVBAR ========= -->

<HR>
<H2>
Package com.google.gwt.http.client
</H2>
Provides the client-side classes and interfaces for making HTTP requests and 
processing the associated responses.
<P>
<B>See:</B>
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="#package_description"><B>Description</B></A>
<P>

<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2">
<B>Interface Summary</B></FONT></TH>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../../../../com/google/gwt/http/client/RequestCallback.html" title="interface in com.google.gwt.http.client">RequestCallback</A></B></TD>
<TD>The primary interface a caller must implement to receive a response to a
 <A HREF="../../../../../com/google/gwt/http/client/Request.html" title="class in com.google.gwt.http.client"><CODE>Request</CODE></A>.</TD>
</TR>
</TABLE>
&nbsp;

<P>

<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2">
<B>Class Summary</B></FONT></TH>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../../../../com/google/gwt/http/client/Header.html" title="class in com.google.gwt.http.client">Header</A></B></TD>
<TD>Class for describing an HTTP header.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../../../../com/google/gwt/http/client/Request.html" title="class in com.google.gwt.http.client">Request</A></B></TD>
<TD>An HTTP request that is waiting for a response.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../../../../com/google/gwt/http/client/RequestBuilder.html" title="class in com.google.gwt.http.client">RequestBuilder</A></B></TD>
<TD>Builder for constructing <A HREF="../../../../../com/google/gwt/http/client/Request.html" title="class in com.google.gwt.http.client"><CODE>Request</CODE></A> objects.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../../../../com/google/gwt/http/client/RequestBuilder.Method.html" title="class in com.google.gwt.http.client">RequestBuilder.Method</A></B></TD>
<TD>HTTP request method constants.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../../../../com/google/gwt/http/client/Response.html" title="class in com.google.gwt.http.client">Response</A></B></TD>
<TD>Wrapper which provides access to the components of an HTTP response.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../../../../com/google/gwt/http/client/URL.html" title="class in com.google.gwt.http.client">URL</A></B></TD>
<TD>Utility class for the encoding and decoding URLs in their entirety or by
 their individual components.</TD>
</TR>
</TABLE>
&nbsp;

<P>

<TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
<TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
<TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2">
<B>Exception Summary</B></FONT></TH>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../../../../com/google/gwt/http/client/RequestException.html" title="class in com.google.gwt.http.client">RequestException</A></B></TD>
<TD>RequestException is the superclass for the HTTP request related exceptions.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../../../../com/google/gwt/http/client/RequestPermissionException.html" title="class in com.google.gwt.http.client">RequestPermissionException</A></B></TD>
<TD>Exception thrown when the <A HREF="../../../../../com/google/gwt/http/client/RequestBuilder.html" title="class in com.google.gwt.http.client"><CODE>RequestBuilder</CODE></A> attempts to make a request
 to a URL which violates the <a
 href="http://en.wikipedia.org/wiki/Same_origin_policy">Same-Origin Security
 Policy</a>.</TD>
</TR>
<TR BGCOLOR="white" CLASS="TableRowColor">
<TD WIDTH="15%"><B><A HREF="../../../../../com/google/gwt/http/client/RequestTimeoutException.html" title="class in com.google.gwt.http.client">RequestTimeoutException</A></B></TD>
<TD>Thrown to indicate that an HTTP request has timed out.</TD>
</TR>
</TABLE>
&nbsp;

<P>
<A NAME="package_description"><!-- --></A><H2>
Package com.google.gwt.http.client Description
</H2>

<P>
Provides the client-side classes and interfaces for making HTTP requests and 
processing the associated responses. 

<p>
Most applications will be interested in the <A HREF="../../../../../com/google/gwt/http/client/Request.html" title="class in com.google.gwt.http.client"><CODE>Request</CODE></A>, <A HREF="../../../../../com/google/gwt/http/client/RequestBuilder.html" title="class in com.google.gwt.http.client"><CODE>RequestBuilder</CODE></A>, 
<A HREF="../../../../../com/google/gwt/http/client/RequestCallback.html" title="interface in com.google.gwt.http.client"><CODE>RequestCallback</CODE></A> and <A HREF="../../../../../com/google/gwt/http/client/Response.html" title="class in com.google.gwt.http.client"><CODE>Response</CODE></A> classes.
</p>

<h2>Caveats</h2>
<h3>Same-Origin Security Policy</h3>
Modern web browsers restrict client-side scripts from accessing items outside
of their source origin.  This means that a script loaded from <code>www.foo.com</code> cannot access
content from <code>www.bar.com</code>.  For more details please see, <a
href="http://en.wikipedia.org/wiki/Same_origin_policy">Same-Origin Security
Policy</a>.

<h3>Pending Request Limit</h3>
Modern web browsers are limited to having only two HTTP requests outstanding at
any one time.  If your server experiences an error that prevents it from sending 
a response, it can tie up your outstanding requests.  If you are concerned about 
this, you can always set timeouts for the request via <A HREF="../../../../../com/google/gwt/http/client/RequestBuilder.html#setTimeoutMillis(int)"><CODE>RequestBuilder.setTimeoutMillis(int)</CODE></A>.

<h3>Required Module</h3>
Modules that use the classes and interfaces in this package should inherit
the <code>com.google.gwt.http.HTTP</code> module.

<blockquote><pre>&lt;module&gt;
  &lt;!-- other inherited modules, such as com.google.gwt.user.User --&gt;
  &lt;inherits name="com.google.gwt.http.HTTP"/&gt;
  &lt;!-- additional module settings --&gt;
&lt;/module&gt;
</pre></blockquote>
 
<h2>Quick Howto's</h2>
<h3>How should I write a RequestCallback handler class?</h3>
The following code shows how a <A HREF="../../../../../com/google/gwt/http/client/RequestCallback.html" title="interface in com.google.gwt.http.client"><CODE>RequestCallback</CODE></A> instance should be written.
<blockquote><pre>public class RequestCallbackExample implements RequestCallback {

  private static final int STATUS_CODE_OK = 200;

  public void onError(Request request, Throwable exception) {
    if (exception instanceof RequestTimeoutException) {
      // handle a request timeout
    } else {
      // handle other request errors
    }
  }

  public void onResponseReceived(Request request, Response response) {
    if (STATUS_CODE_OK == response.getStatusCode()) {
      // handle OK response from the server 
    } else {
      // handle non-OK response from the server
    }
  }
}
</pre></blockquote>

<h3>How do I make a GET request?</h3>
The following example demonstrates how to perform an HTTP GET request.
<blockquote><pre>public class GetExample implements EntryPoint {
  public static final int STATUS_CODE_OK = 200;
  
  public static void doGet(String url) {
    RequestBuilder builder = new RequestBuilder(RequestBuilder.GET, url);

    try {
      Request response = builder.sendRequest(null, new RequestCallback() {
        public void onError(Request request, Throwable exception) {
          // Code omitted for clarity
        }

        public void onResponseReceived(Request request, Response response) {
          // Code omitted for clarity
        }
      });
    } catch (RequestException e) {
      // Code omitted for clarity
    }
  }

  public void onModuleLoad() {
    doGet("/");
  }
}
</pre></blockquote>

<h3>How do I make a POST request?</h3>
The following example demonstrates how to perform an HTTP POST request.
<blockquote><pre>public class PostExample {
  public static void doPost(String url, String postData) {
    RequestBuilder builder = new RequestBuilder(RequestBuilder.POST, url);

    try {
      builder.setHeader("Content-Type", "application/x-www-form-urlencoded");
      Request response = builder.sendRequest(postData, new RequestCallback() {

        public void onError(Request request, Throwable exception) {
          // code omitted for clarity
        }

        public void onResponseReceived(Request request, Response response) {
          // code omitted for clarity
        }
      });
    } catch (RequestException e) {
      Window.alert("Failed to send the request: " + e.getMessage());
    }
  }

  public void onModuleLoad() {
    doPost("/", "Hello World!");
  }
}
</pre></blockquote>

<h3>How do I use request timeouts?</h3>
The following example demonstrates how to use the timeout feature.
<blockquote><pre>public class TimeoutExample implements EntryPoint {
  public static void doGetWithTimeout(String url) {
    RequestBuilder builder = new RequestBuilder(RequestBuilder.GET, url);

    try {
      /*
       * wait 2000 milliseconds for the request to complete
       */
      builder.setTimeoutMillis(2000);
      
      Request response = builder.sendRequest(null, new RequestCallback() {
        public void onError(Request request, Throwable exception) {
          if (exception instanceof RequestTimeoutException) {
            // handle a request timeout
          } else {
            // handle other request errors
          }
        }

        public void onResponseReceived(Request request, Response response) {
          // code omitted for clarity
        }
      });
    } catch (RequestException e) {
      Window.alert("Failed to send the request: " + e.getMessage());
    }
  }

  public void onModuleLoad() {
    doGetWithTimeout("/");
  }
}
</pre></blockquote>

<h3>How do I construct a string for use in a query or POST body?</h3>
The following example demonstrates how to build a x-www-form-urlencoded string that can be used as a query string or as the body of a POST request.
<blockquote><pre>public class QueryAndFormDataExample {
  
  public static interface Entry {
    String getName();
    String getValue();
  }

  public static String buildQueryString(Entry[] queryEntries) {
    StringBuffer sb = new StringBuffer();

    for (int i = 0, n = queryEntries.length; i < n; ++i) {
      Entry queryEntry = queryEntries[i];

      if (i > 0) {
        sb.append("&");
      }

      // encode the characters in the name
      String encodedName = URL.encodeComponent(queryEntry.getName());
      sb.append(encodedName);
      
      sb.append("=");
    
      // encode the characters in the value
      String encodedValue = URL.encodeComponent(queryEntry.getValue());
      sb.append(encodedValue);
    }
    
    return sb.toString();
  }
}
</pre></blockquote>

<h3>How can I make a <A HREF="../../../../../com/google/gwt/http/client/RequestBuilder.html" title="class in com.google.gwt.http.client"><CODE>RequestBuilder</CODE></A> send a request other than GET or POST?</h3>
The following example demonstrates how to allow an HTTP request other than a GET or a POST to be made.  <em>Beware: if you plan on supporting Safari, you cannot use this scheme.</em>
<blockquote><pre>public class RequestBuilderForAnyHTTPMethodTypeExample extends RequestBuilder {
  
  /**
   * Constructor that allows a developer to override the HTTP method 
   * restrictions imposed by the RequestBuilder class.  Note if you override the 
   * RequestBuilder's HTTP method restrictions in this manner, your application 
   * may not work correctly on Safari browsers.
   * 
   * @param httpMethod any non-null, non-empty string is considered valid
   * @param url any non-null, non-empty string is considered valid
   *
   * @throws IllegalArgumentException if httpMethod or url are empty
   * @throws NullPointerException if httpMethod or url are null
   */
  public RequestBuilderForAnyHTTPMethodTypeExample(String httpMethod, String url) {
    super(httpMethod, url);
  }
}
</pre></blockquote>
<P>

<P>
<DL>
</DL>
<HR>


<!-- ======= START OF BOTTOM NAVBAR ====== -->
<A NAME="navbar_bottom"><!-- --></A>
<A HREF="#skip-navbar_bottom" title="Skip navigation links"></A>
<TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
<TR>
<TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
<A NAME="navbar_bottom_firstrow"><!-- --></A>
<TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
  <TR ALIGN="center" VALIGN="top">
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Package</B></FONT>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <FONT CLASS="NavBarFont1">Class</FONT>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
  <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
  </TR>
</TABLE>
</TD>
<TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
</EM>
</TD>
</TR>

<TR>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
&nbsp;<A HREF="../../../../../com/google/gwt/dom/client/package-summary.html"><B>PREV PACKAGE</B></A>&nbsp;
&nbsp;<A HREF="../../../../../com/google/gwt/i18n/client/package-summary.html"><B>NEXT PACKAGE</B></A></FONT></TD>
<TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
  <A HREF="../../../../../index.html?com/google/gwt/http/client/package-summary.html" target="_top"><B>FRAMES</B></A>  &nbsp;
&nbsp;<A HREF="package-summary.html" target="_top"><B>NO FRAMES</B></A>  &nbsp;
&nbsp;<SCRIPT type="text/javascript">
  <!--
  if(window==top) {
    document.writeln('<A HREF="../../../../../allclasses-noframe.html"><B>All Classes</B></A>');
  }
  //-->
</SCRIPT>
<NOSCRIPT>
  <A HREF="../../../../../allclasses-noframe.html"><B>All Classes</B></A>
</NOSCRIPT>


</FONT></TD>
</TR>
</TABLE>
<A NAME="skip-navbar_bottom"></A>
<!-- ======== END OF BOTTOM NAVBAR ======= -->

<HR>

</BODY>
</HTML>
